Crate termwiz

source ·
Expand description

Terminal Wizardry

This is a rust crate that provides a number of support functions for applications interested in either displaying data to a terminal or in building a terminal emulator.

It is currently in active development and subject to fairly wild sweeping changes.

Included functionality:

  • Surface models a terminal display and its component Cells
  • Terminal attributes are aware of modern features such as True Color, Hyperlinks and will also support sixel and iterm style terminal graphics display.
  • Surfaces include a log of Changes and an API for consuming and applying deltas. This is a powerful building block for synchronizing screen instances.
  • Escape sequence parser decodes inscrutable escape sequences and gives them semantic meaning, making the code that uses them clearer. The decoded escapes can be re-encoded, allowing applications to start with the semantic meaning and emit the appropriate escape sequence without embedding obscure binary bytes.
  • Capabilities allows probing for terminal capabilities that may not be included in the system terminfo database, and overriding them in an embedding application.
  • Terminal trait provides an abstraction over unix style ttys and Windows style console APIs. Changes from Surface can be rendered to Terminals. Terminals allow decoding mouse and keyboard inputs in both blocking or non-blocking mode.
  • Widget trait allows composition of UI elements at a higher level.
  • LineEditor provides line editing facilities similar to those in the unix shell.

Features

  • widgets - enables the widget layout and related traits
  • use_serde - makes a number of structs serde serializable

Re-exports

pub use error::Context;
pub use error::Error;
pub use error::Result;

Modules

Terminal Capabilities
Model a cell in the terminal display
Colors for attributes
This module provides the ability to parse escape sequences and attach semantic meaning to them. It can also encode the semantic values as escape sequences. It provides encoding and decoding functionality only; it does not provide terminal emulation facilities itself.
Handling hyperlinks. This gist describes an escape sequence for explicitly managing hyperlinks: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5fedaA We use that as the foundation of our hyperlink support, and the game plan is to then implicitly enable the hyperlink attribute for a cell as we recognize linkable input text during print() processing.
Images. This module has some helpers for modeling terminal cells that are filled with image data. We’re targeting the iTerm image protocol initially, with sixel as an obvious follow up. Kitty has an extensive and complex graphics protocol whose docs are here: https://github.com/kovidgoyal/kitty/blob/master/docs/graphics-protocol.rst Both iTerm2 and Sixel appear to have semantics that allow replacing the contents of a single chararcter cell with image data, whereas the kitty protocol appears to track the images out of band as attachments with z-order.
This module provides an InputParser struct to help with parsing input received from a terminal.
Making it a little more convenient and safe to query whether something is a terminal teletype or not. This module defines the IsTty trait and the is_tty method to return true if the item represents a terminal.
A datastructure for holding key map entries
The LineEditor struct provides line editing facilities similar to those in the unix shell.
An abstraction over a terminal device

Macros